<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <meta content="text/html; charset=ISO-8859-1"
      http-equiv="Content-Type">
    <title>Nine-Patch</title>
    <meta name="order" content="13" />
  </head>
  <body>
    <h2>Nine-Patch</h2>
    <p>Nine Patch is an image format that adds extra information into a normal image file to define which part of
    it should be scaled when the image is used in a size larger than its original size. The technique in using this format
    is also implemented in the core of the Android OS.
    </p>
    <p>More information about this format can be found at:<br/><a
href="http://developer.android.com/guide/topics/graphics/2d-graphics.html#nine-patch">http://developer.android.com/guide/topics/graphics/2d-graphics.html#nine-patch</a></p>
    <p>
      It is very simple and flexible to make a stencil based on an existing bitmap image by defining the scaling part using the Nine-patch format.
      Starting from version 2.0, Pencil also provides built-in behaviors and tool to support this technique for
      developers to create their awesome collections. There are already
      many collections using this technique in Pencil repository such as
      the iOS UI Stencils.</p>
    <h3>Creating a simple stencil using Nine-patch</h3>
    <p>
    
    Suppose that we have the original rounded corner rectangle image as the following one and we want to create a shape base on this image and can be scaled to desired size while maintaining the corner radius.
    <br/>
    <img
        src="../images/Main_html_2b605a48.png"
        name="graphics10" alt="" border="0" height="107" width="107">
    <br/><br/>
    <h4>1. Defining Nine-patch</h4>        
      The first step is to create a Nine-patch from this image by adding 4 black lines to its border to define the scaling and padding areas (Please note that, the correct with of these lines must be 1 pixel. For the purpose of illustration, lines are enlarged in this tutorial).
    <br/>        
    <img
src="../images/Main_html_m2af8dc4a.png"
        name="graphics9" alt="" border="0" height="113" width="113"><br/><br/>
    In this nine-patch, top and left lines are used to divide the rectangle to nine pieces while bottom and right lines are used to define the bound. </p>
    <h4>2. Generating JS code</h4>
    <p>
        The next step is to use Pencil-provided tool to load this nine-patch image and generate JavaScript code containing the nine-patch data in a structure
        that is compatible with Pencil built-in implementation for nine-patch.
    </p>
    <p>
        Go to <b>Tools &#187; Developer Tools &#187; N-Path Script Generator...</b> to launch the tool and load the image above. Code generated by this tool should be
        copied and used in the stencil. After parsing you can see that the images are sliced into 9 pieces: </p>
    <p> <img
src="../images/Main_html_1d59ad4c.png"
        name="graphics12" alt="" border="0" height="113" width="113"><br
        clear="left"><br/><br/>
      These pieces are sliced based on the lines on the top and left side of the images: </p>
      <ul>
    <li>The 1, 3, 7, 9 piece will be the same when scaling box. </li>
    <li>The width of 2, 5, 8 piece will be scale based on the ratio
      between old width and new width. </li>
    <li>The height of 4, 5, 6 piece will be scale based on the ratio
      between old height and new height. </li>
      </ul>
    <h4>3. Use the generated code in your stencil</h4>
    <p>The easiest way to use the generated code is to define a set of nine-patches in the collection level by using the <code>&lt;Script&gt;</code> tag. The generated code in the above step is used as the value of the "sample" property in the following example.</p>
<pre name="code" class="xml">
<![CDATA[
<Script comments="N Patches">
collection.nPatches = {
    sample: {"w":35,"h":35,"p1":{"x":15,"y":16},"p2":{"x":20,"y":22},"patches":[[{"url":"","w":17,"h":17,"scaleX":false,"scaleY":false},{"url":"","w":1,"h":17,"scaleX":true,"scaleY":false},{"url":"","w":17,"h":17,"scaleX":false,"scaleY":false}],[{"url":"","w":17,"h":1,"scaleX":false,"scaleY":true},{"url":"","w":1,"h":1,"scaleX":true,"scaleY":true},{"url":"","w":17,"h":1,"scaleX":false,"scaleY":true}],[{"url":"","w":17,"h":17,"scaleX":false,"scaleY":false},{"url":"","w":1,"h":17,"scaleX":true,"scaleY":false},{"url":"","w":17,"h":17,"scaleX":false,"scaleY":false}]],"lastScaleX":1,"lastScaleY":1}
}
</Script>
]]>
</pre>
    <p>Then in the code for the stencil that uses this nine-patch, you can simply use built-in supports of Pencil to simplify the code.</p>
<pre name="code" class="xml">
<![CDATA[
<Shape id="sample" displayName="NPathSampe" icon="Icons/sample.png">
  <Properties>
    <PropertyGroup>
      <Property name="box" type="Dimension">320,44</Property>
    </PropertyGroup>

    <PropertyGroup name="Text">
      <Property name="text" displayName="Text" type="PlainText">Content</Property>
      <Property name="textFont" displayName="Default Font"
                type="Font">Helvetica|bold|normal|20px</Property>
    </PropertyGroup>
  </Properties>
  <Behaviors>
    <For ref="bg">
      <NPatchDomContent>
        <Arg>collection.nPatches.sample</Arg>
        <Arg>$box</Arg>
      </NPatchDomContent>
    </For>
    <For ref="text">
      <TextContent>$text</TextContent>
      <Font>$textFont</Font>
      <Fill>Color.fromString('#ffffffff')</Fill>
      <BoxFit>
        <Arg>getNPatchBound(collection.nPatches.sample, $box)</Arg>
        <Arg>new Alignment(1, 1)</Arg>
      </BoxFit>
    </For>
  </Behaviors>
  <p:Content xmlns="http://www.w3.org/2000/svg">
    <g id="bg"></g>
    <text id="text" />
  </p:Content>
</Shape>
]]>
</pre>
    
    <p>
        The <code><a href="~/wiki/ref/Behaviors.html#npatchdomcontent">NPatchDomContent</a></code> behavior bases on the provided nine-patch and dimension to perform calculation of
        scaling and then fill the <code>bg</code> element with images generated from the nine-patch.</span>
    </p>
    <p>The <code>getNPatchBound</code> utility function is used here to obtain the bound defined by the bottom-right markers in the nine-patch to place the text in the correct position.</p>
    <p> <img
src="../images/Main_html_m1c0fecf0.png"
        name="graphics14" alt="" border="0" height="113" width="113"><br
        clear="left">
    <h4>4. More complex nine-patch</h4>
    <p>Dispite the name of the technique, nine-patch can be defined so that it sliced to an unlimited number of pieces depending on the nature of the shape we are creating. Suppose that
    we have the following bitmap and we would like to have it scale in a way that in the vertical direction, only blue and red parts are scaled while cyan area are remain unscaled and in the horizontal
    direction the whole length of the image should be scaled.</p>
    <p> <img
src="../images/Main_html_2c628959.png"
        name="graphics11" alt="" border="0" height="128" width="85"><br
        clear="left">
    </p>
    <p>To do this, we can add the scaling markers to the images as in the following nine-patch:</p>
    <p> <img
src="../images/Main_html_m58ebc780.png"
        name="graphics16" alt="" border="0" height="128" width="89"><br
        clear="left">
      <span>If we do not add right and bottom lines,
        <code>getNPatchBound</code> will return the bound that containing the whole image.</span> </p>
  </body>
</html>
